home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / dmedia / dmicwork.z / dmicwork
Encoding:
Text File  |  2002-10-03  |  6.4 KB  |  133 lines
  1.  
  2.  
  3.  
  4. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ddddmmmmIIIICCCCWWWWoooorrrrkkkk,,,, - call the image converter and have it perform a task
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////ddddmmmm____iiiimmmmaaaaggggeeeeccccoooonnnnvvvveeeerrrrtttt....hhhh>>>>
  13.  
  14.      DDDDMMMMssssttttaaaattttuuuussss ddddmmmmIIIICCCCWWWWoooorrrrkkkk((((DDDDMMMMiiiimmmmaaaaggggeeeeccccoooonnnnvvvveeeerrrrtttteeeerrrr ccccoooonnnnvvvveeeerrrrtttteeeerrrr,,,, iiiinnnntttt ****ssssttttaaaattttuuuussss____ffffllllaaaaggggssss,,,,
  15.      iiiinnnntttt ****nnnn____iiiinnnnppppuuuutttt____ddddeeeeqqqquuuueeeeuuuueeeedddd,,,, iiiinnnntttt ****nnnn____oooouuuuttttppppuuuutttt____eeeennnnqqqquuuueeeeuuuueeeedddd))));;;;
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  18.      This function calls into the image converter and has it perform a task
  19.      (such as a compress or uncompress) on the buffers that have previously
  20.      been sent to it using dmICSend.
  21.  
  22.      _c_o_n_v_e_r_t_e_r    the converter instance
  23.  
  24.      _s_t_a_t_u_s__f_l_a_g_s bit field flags returning information about what transpired
  25.                   during the dmICWork call, especially in the event of an
  26.                   error.  Flags include: DM_IC_WORK_NO_STATUS,
  27.                   DM_IC_WORK_ERROR, DM_IC_WORK_NOT_NEEDED,
  28.                   DM_IC_WORK_INSUFFICIENT_INPUT_DATA, and
  29.                   DM_IC_WORK_INSUFFICIENT_OUTPUT_SPACE.
  30.  
  31.      _n__i_n_p_u_t__d_e_q_u_e_u_e_d
  32.                   the number of source buffers dequeued by this dmICWork call
  33.  
  34.      _n__o_u_t_p_u_t__e_n_q_u_e_u_e_d
  35.                   the number of output buffers enqueued by this dmICWork call
  36.  
  37. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  38.      This call will have the converter actually perform the conversion on the
  39.      srcBuffer previously sent by ddddmmmmIIIICCCCSSSSeeeennnndddd.  Note that this call is only
  40.      necessary if the default threaded model of dmIC has been turned off, so
  41.      that there is only one thread.  This is done by setting a DM_IC_THREADS
  42.      dmParam to be DM_IC_THREADS_DISABLED, and then calling ddddmmmmIIIICCCCSSSSeeeettttCCCCoooonnnnvvvvPPPPaaaarrrraaaammmmssss
  43.      on the DMimageconverter immediately after it is created with ddddmmmmIIIICCCCCCCCrrrreeeeaaaatttteeee.
  44.      See the source code example below.
  45.  
  46.      ddddmmmmIIIICCCCWWWWoooorrrrkkkk is a synchronous operation.  When ddddmmmmIIIICCCCWWWWoooorrrrkkkk returns, the
  47.      conversion is finished, and ddddmmmmIIIICCCCRRRReeeecccceeeeiiiivvvveeee can be used to pick up the output
  48.      if an output buffer has been enqueued.
  49.  
  50.      ddddmmmmIIIICCCCWWWWoooorrrrkkkk must NOT be called in the default threaded dmIC model.
  51.  
  52.      ddddmmmmIIIICCCCWWWWoooorrrrkkkk will attempt to do the smallest amount of work possible while
  53.      still achieving something.  For the vast majority of image converters,
  54.      this means it dequeues exactly one buffer, compresses or uncompresses
  55.      that buffer, and enqueues exactly one result buffer.
  56.  
  57.      Several types of errors can occur in ddddmmmmIIIICCCCWWWWoooorrrrkkkk, and these will result
  58.      various status flags being returned.  For example, the input queue could
  59.      be empty (DM_IC_WORK_INSUFFICIENT_INPUT_DATA), or the output queue could
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ddddmmmmIIIICCCC((((3333ddddmmmm))))                                                            ddddmmmmIIIICCCC((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      be full (DM_IC_WORK_INSUFFICIENT_OUTPUT_SPACE).  In the case of a
  75.      hardware accelerated image converter, ddddmmmmIIIICCCCWWWWoooorrrrkkkk will return DM_SUCCESS,
  76.      and will also set the status flag to be DM_IC_WORK_NOT_NEEDED, since the
  77.      hardware has already performed the task. In this case there will be no
  78.      buffers dequeued or enqueued.
  79.  
  80. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  81.      The following source code suppresses the default threaded behavior of
  82.      dmIC, and uses the ddddmmmmIIIICCCCWWWWoooorrrrkkkk function to perform the tasks that by default
  83.      would have been done by a separate thread:
  84.  
  85.        /*
  86.         * Create the image converter from the index
  87.         */
  88.        if (dmICCreate(convIndex, &imageConverter) != DM_SUCCESS)
  89.            fatal("dmICCreate failed for our imageConverter");
  90.  
  91.        ... some code not included ...
  92.  
  93.        /*
  94.         * Set the "disable sproc" converter param
  95.         */
  96.        dmParamsCreate(&cPrms);
  97.        dmParamsSetEnum(cPrms, DM_IC_THREADS, DM_IC_THREADS_DISABLED);
  98.        if (dmICSetConvParams(imageConverter, cPrms) != DM_SUCCESS)
  99.            fatal("should never occur");
  100.  
  101.        ... some code not included ...
  102.  
  103.        if (dmICSend(imageConverter, srcBuf, NULL, NULL) != DM_SUCCESS)
  104.            fatal("dmICSend failed");
  105.        dmBufferFree(srcBuf);
  106.  
  107.        if (dmICWork(imageConverter, &status, &nIn, &nOut) != DM_SUCCESS)
  108.            fatal("dmICWork failed");
  109.  
  110.        ... use system call "select()" here to wait for results ...
  111.  
  112.        if (dmICReceive(imageConverter, &dstBuf) != DM_SUCCESS)
  113.            fatal("dmICReceive failed");
  114.  
  115.  
  116. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  117.      dmBufferAllocate(3dm), dmICSend(3dm), dmICSetSrcParams(3dm),
  118.      dmICSetDstParams(3dm), dmICSetConvParams(3dm), dmICReceive(3dm).
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.